docs(skills): improve drafting skills from signal log patterns 2026-08-01 - #450

…ements (#487)

* docs(skills): reduce automation noise and consolidate drafting improvements

Recurring docs agents were producing more PRs and Slack messages than the
team could absorb. Three systemic causes, plus a batch of GitBook-era
migration artifacts that left several skills unable to run as written.

Shared conventions (skill-authoring-guidelines.md):
- Add "One standing PR per automation": stable branch and title, look
  before creating, add to the existing PR rather than opening another.
- Invert "Slack notifications" to actionable-only. The old rule required
  posting on every run and was the direct cause of the channel noise. Its
  silent-failure rationale is preserved by requiring a run log instead.
- Rewrite "Log availability" so outer loops read the log branch rather
  than main, and never merge the standing log PR as a workflow step.

Cron correctness:
- `0 17 1-7 * 1` is not "first Monday". Cron ORs day-of-month with
  day-of-week, so it fired ~11 times a month and produced four
  conflicting PRs in six days. Replace with `0 17 * * 1` plus an
  in-skill first-week guard in improve-drafting-skills,
  improve-aeo-crosslink-skill, and improve-404-monitor-skill.

PR reuse applied to: improve-drafting-skills, weekly-404-monitor,
afdocs-fix, sync-error-docs, sync_terminology, sync-openapi-spec,
improve-aeo-crosslink-skill, improve-404-monitor-skill. update-changelog
keeps one PR per release (correct) but now detects stacked release PRs.

Slack volume: aeo_crosslink_audit no longer posts on no-change runs;
weekly-404-monitor gates on threshold and folds its Phase 2 results into
a single message instead of two; afdocs-audit posts only on regression or
a blocked audit, backed by a new run log for the baseline.

Migration artifacts: a find-and-replace during the GitBook-to-Astro move
substituted descriptions into file paths. sync-error-docs referenced
`astro.config.mjs (sidebar config)` and `vercel.json (redirects)` as real
paths, had an invalid grep, and still called the GitBook API - it could
not have succeeded. Also corrected the sidebar location to src/sidebar.ts,
dropped the GITBOOK_TOKEN dependency, and fixed dead
`.warp/references/terminology.md` paths in four skills.

Consolidates PRs #450, #454, #468, and #484, which all edited
draft_docs/SKILL.md and conflicted with each other. Overlapping patterns
were merged rather than stacked, and PR #468's frontmatter-description
edits were dropped as already superseded on main.

Co-Authored-By: Warp Agent <agent@warp.dev>

* docs(skills): document the deployed monthly cron for improve-drafting-skills

The schedule was deployed as `0 15 1 * *` (the 1st of each month) rather
than the `0 17 * * 1` + first-week-guard combination the skill documented.
Both are correct and both fire exactly once a month, but the docs and the
deployed schedule disagreed.

Documented the deployed expression. Restricting only day-of-month is
unambiguous because day-of-week stays `*`, so there is no ORing hazard. The
tradeoff is noted: the 1st can land on a weekend, delaying review.

Kept the first-week guard as a safety net and explained why, since it no
longer trips on its own: it is what would narrow a day-of-week expression
back to the first Monday, and it contains the blast radius if the
day-of-month/day-of-week ORing mistake is ever reintroduced. Reworded the
guard's skip message, which still referenced 'first Monday'.

Co-Authored-By: Warp Agent <agent@warp.dev>

* docs(skills): treat a log-branch fetch failure as blocked, not a stale fallback

Review catch on improve-aeo-crosslink-skill: its step 0 said to fall back to
the log copy in the current checkout when the branch fetch fails. That copy
comes from `main` — precisely the truncated history the branch read exists to
avoid — so the fallback reintroduced the problem this PR set out to fix. The
file also contradicted itself: its Slack section already listed 'could not
fetch the log branch' as a blocked-run example while step 0 said not to abort.

The failure mode is quiet, which is what makes it worth fixing. A short log
still parses; only the counts change. The run then either drops below the
8-entry minimum and reports 'too early to analyze', or clears the minimum on
stale entries and proposes skill edits from an incomplete picture. Both look
like ordinary outcomes, so nobody investigates.

Both outer loops that read a log branch now stop before analysis on a fetch
failure and post the blocked-run message. improve-drafting-skills already had
this behavior documented and is unchanged.

Also generalized the rule in the authoring guidelines, since this is a class of
bug rather than a one-off: do not adopt a fallback that is quieter but less
correct than failing. The test is whether the fallback can change the answer
ratherratherratherratherratherratherratherratherratherratherratherratverage
transparently — proceeding on one source signal and recording the gap — remain
fine, because the reader can see what was missing.

Co-Authored-By: Warp Agent <agent@warp.dev>

---------

Co-authored-by: Warp Agent <agent@warp.dev>